Bug Proofing Visual Basic: A Guide to Error Handling and Prevention
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471323519
Publication Date: 11/01/98

CHAPTER 7
Comments

Comments help reconcile the two conflicting goals of writing code that can be executed efficiently by a computer and writing code that is understandable to a human. Header-style comments at the beginning of files and routines give readers perspective that helps them better understand the code that follows. Inline comments within the code provide detail the reader needs to easily understand the program.

By increasing the readers’ comprehension, comments reduce the chances of bugs being introduced into the code. Better understanding of the code lets developers find bugs faster and fix them more quickly with less chance of error.

This chapter gives general commenting guidelines and standard formats for header-style comments. The exact format does not matter as much as your using some sort of consistent commenting system.

The first three sections that follow describe header-style comments. Use these comments at the beginning of files, routines, and event handlers to give context and background information to the reader. These three sections include example header comments. Appendix B, “Header Comment Templates,” contains blank comment templates. You can also download copies of these templates from the book’s Web site at www.vb-helper.com/err.htm. You can then paste them into your programs and fill in the blanks.

The remaining sections in this chapter explain guidelines that are applicable to comments in general.

Comment Files

Begin each file with a header comment giving an overview of the file’s contents. This comment should include identifying information, description of purpose, entry points, dependencies, known issues, method overview, and declarations.

Identifying Information

Identifying information includes the filename, copyright information, creation date, list of authors, and security level if applicable. It should include any text that you want to appear on printed copies of the file.

Do not underestimate the importance of including the filename here. The name may seem obvious to you when you print the file, but the printout may be copied and sent to others who will need to know where the file is.

If your printer has an option to include the date and the filename in a header or footer on each page, use it. Then you can determine the filename even if you only have a single page from the middle of the file.

Description

The description should explain the file’s overall purpose or theme. This should be a short sentence or a paragraph at most. If you cannot explain a module’s general purpose in a few sentences, it probably does not represent a clear concept that developers can easily understand. In that case, it would be better to break the file into two or more smaller files, each having a clear purpose.

For .BAS modules, the description should explain the file’s theme. For example, “Routines for manipulating three-dimensional matrices.”

For .FRM modules, the description should explain what the form is for and what it does. For example, “New job input form where the user enters information to create a new job.”

For .CLS modules, the description should explain what the class represents. For instance, “Billing object that represents a single bill to be sent to a customer.” It can also include a very brief discussion of the class responsibilities. The method section described shortly contains a more detailed explanation of responsibilities and collaborations.

Entry Points

This section lists the public variables, properties, and routines the module exposes to the rest of the program. It provides a brief description of the purposes of these public items.

This section can be difficult to maintain, particularly early in the development process when programmers change the file’s interface frequently. On the other hand, it can also provide a framework for the developers who are building the module. The entry points can be defined and documented during the low-level design process. Then developers can work to make the variables and routines in the module meet these interface goals. Many bugs occur when one routine uses another incorrectly. Defining the public interface for a module early can reduce the chances of misunderstandings between developers and produce more reliable interactions between routines.

Dependencies

This section contains a list of dependencies the file has to other modules. For example, if the code uses functions contained in a certain .BAS module, that module should be listed here.

The dependency list can be helpful in finding bugs. If you trace a problem to this module, the list tells you which other files may be involved. It also lets you know that you may need to update this file if one of the files in the dependency list has changed.

The dependency list is the hardest part of the header comment to maintain. Any developer who changes this module must review the list to make sure the file dependencies are still correct.

Known Issues

Known issues include unsolved bugs, bottlenecks, possible future enhancements, and descriptions of any other issues that should be addressed later. These issues should be described very briefly. If one is particularly complicated, the comment should refer to another source, like a bug tracking system, for further detail.

Method

The method section describes any particularly complex details that make sense on a file level. This may include such things as an explanation of complex algorithms that are not described within the code, an overview of how different routines within the module interact, or a description of a data structure used in the module. Provide references to books or articles if possible to keep this section brief.

For class modules, this section should include a description of the class responsibilities, collaborations, and interactions with other objects in the system.

Declarations

Standard declaration sections follow the main parts of the header information. These sections group type definitions, variable declarations, and constant definitions.

Some of these sections do not apply to all files. For example, forms cannot declare public user-defined types so you do not need a section for them.

Rather than placing API declarations in separate sections, put them all together. For instance, instead of putting API type definitions in one section and API function declarations in another, put them all in a separate API section. This makes updating the code easier when API functions change during different releases of the operating system.